home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Diamond Collection / The Diamond Collection (Software Vault)(Digital Impact).ISO / cdr36 / sqbe_d.zip / QBE.DOC < prev    next >
Text File  |  1995-02-07  |  58KB  |  1,500 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.                               ===================
  18.                                S U P E R   Q B E
  19.                               ===================
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.                       The Super Query By Example Templates
  27.  
  28.  
  29.                                   Version 1.0
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.                                       for
  41.  
  42.                               Clarion for Windows
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.                  (c) Copyright 1995 - BoxSoft Development Inc.                                -----------------
  58.                                Table of Contents
  59.                                -----------------
  60.  
  61.      Introduction  ..........................                           -1-
  62.  
  63.      Installation  ..........................                           -2-
  64.           Distributing Your Applications ...............                -2-
  65.  
  66.      What is Query By Example? ....................                     -3-
  67.  
  68.      What are Tags?  .........................                          -5-
  69.  
  70.      Adding QBE to Your Application  .................                  -6-
  71.           Registering the Template ..................                   -6-
  72.           Global Support .......................                        -6-
  73.           Browse Support .......................                        -8-
  74.           Form Support ........................                         -9-
  75.           Optional Tag Filters in a Browse ..............              -11-
  76.           Filtering Tagged in Reports and Processes  .........         -13-
  77.           Showing Only Tagged Records in a Browse  ..........          -15-
  78.           Showing Only Tagged Records in Reports and Processes ....    -16-
  79.  
  80.      Reference Section ........................                        -17-
  81.           Embed Points in QbeForm  ..................                  -17-
  82.           Global Variables ......................                      -18-
  83.           Procedures and Functions using POINTER ...........           -19-
  84.           Procedures and Functions using POSITION  ..........          -21-
  85.           Miscellaneous Procedures and Functions ...........           -23-
  86.  
  87.      Contacting Technical Support  ..................                  -24-
  88.  
  89.  
  90.                                -----------------
  91.                                MAJOR WARNING !!!
  92.                                -----------------
  93.  
  94.      It is very important that you read this manual.  If you follow the
  95.      instructions step-by-step, then the usage is very simple.  It is
  96.      almost IMPOSSIBLE if you try to do it on your own!
  97.  
  98.  
  99.                                    ----------
  100.                                    Disclaimer
  101.                                    ----------
  102.  
  103.      This software is guaranteed to occupy space.  BoxSoft Development Inc.
  104.      offers no other warranties as to its usability or usefulness.  If you
  105.      have difficulty with the software, we promise to help you as much as
  106.      we deem is necessary and possible.  We are not liable for any losses
  107.      of time or money that you may experience due to this software or its
  108.      use.                                   ------------
  109.                                   Introduction
  110.                                   ------------
  111.  
  112.      The SuperQBE Templates enable you to perform ad hoc query operations
  113.      using Clarion for Windows.  This will save you from writing numerous
  114.      reports for your users.  Instead, they can perform a wide variety of
  115.      searches using their regular forms, then print the results using one
  116.      of their standard reports.
  117.  
  118.      There are a number of templates included in this package to provide
  119.      you with the following functionality:
  120.  
  121.      QbeBrowse - This Control template calls a Form procedure for a query
  122.           operation.  After the form returns, it automatically displays
  123.           only the search results in your browse (assuming that you are
  124.           also using the BrowseOptTagFilter).
  125.  
  126.      QbeForm - This Control template is placed on your Form.  It performs
  127.           the majority of the searching operations and interface control. 
  128.           It can tag all matching records, or display each record for you
  129.           optionally to edit it.
  130.  
  131.      BrowseOptTagFilter - This Control template provides a button that
  132.           toggles a Browse between showing "All" records, or just "Tagged"
  133.           records.  It is automatically utilized by the QbeBrowse template.
  134.  
  135.      BrowseTagFilter - This Extension template enables you to display only
  136.           tagged records in a browse.  This differs from the previous
  137.           template in that the filter is always "on".
  138.  
  139.      ProcessTagFilter - This Extension template adds a filter to a Report
  140.           or Process so that only tagged records are used by the procedure. 
  141.           This is similar to the BrowseTagFilter template, except that it
  142.           is specifically used for Report and Process procedures, rather
  143.           than BrowseBox windows.
  144.  
  145.      When records are selected by the QBE system, they are "tagged".  Tags
  146.      may be stored in a "TagFile_ using POINTER", "TagFilePos_ using
  147.      POSITION" (for file drivers that do not support record numbers), or in
  148.      a "BYTE Field in Primary" file of the parent BrowseBox.
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.                                       -1-                                   ------------
  167.                                   Installation
  168.                                   ------------
  169.  
  170.      Whether you've received a diskette or downloaded the file from our
  171.      BBS, Compuserve or any other electronic forum, the installation
  172.      process is the same.  Execute the command:
  173.  
  174.                install <source> <target> <password>
  175.                install a:\ c:\cw password          ie:
  176.  
  177.      <source>       This is the source directory containing the file
  178.                     ZIPPED.EXE.  It will normally be A:\, or C:\DOWNLOAD,
  179.                     or something like that.
  180.  
  181.      <target>       This is the destination, and will normally be your
  182.                     C:\CW directory.  The installation program will place a
  183.                     one or more DLLs into your C:\CW\BIN directory.
  184.  
  185.      <password>     This is the password that you got from BoxSoft or
  186.                     Mitten.  It should be displayed on your invoice, or you
  187.                     can call Mitten for the password.  Make sure you type
  188.                     it in lower case!
  189.  
  190.      You should see the following structure under your CW directory:
  191.  
  192.                C:\CW
  193.                +-SUPER        QBE.TPL
  194.                | +-DOC        QBE.DOC
  195.                | +-EXAMPLES
  196.                | | `-QBE      QBE Example
  197.                | +-INCLUDE    S_QBEEQU.CLW, S_TAG???.CLW
  198.                | +-LIB        S_TAGLIB.LIB
  199.                | `-LIBSRC
  200.                |   `-TAGGING  Tagging Library Source Code
  201.                `-BIN          S_TAGLIB.DLL
  202.  
  203.      After the files are installed, you must update your Redirection file
  204.      to add the C:\CW\SUPER\INCLUDE directory to your CLW entry, and the
  205.      C:\CW\SUPER\LIB directory to your LIB entry.  You can do this using
  206.      the "Setup / Edit Redirection File" pulldown menu option.  The OBJ and
  207.      LIB entries should look like this:
  208.  
  209.                *.lib = c:\cw\obj;c:\cw\lib;c:\cw\super\lib
  210.                *.clw = .;c:\cw\source;c:\cw\super\include
  211.  
  212.  
  213.  
  214.                          Distributing Your Applications
  215.                          ------------------------------
  216.  
  217.      When ship your applications to users, make sure that you include a
  218.      copy of the S_TAGLIB.DLL file from your C:\CW\BIN directory.
  219.  
  220.  
  221.  
  222.  
  223.  
  224.                                       -2-                            -------------------------
  225.                            What is Query By Example?
  226.                            -------------------------
  227.  
  228.      Query By Example, or "QBE", is used to perform ad hoc searches for
  229.      records in your data files.  It uses a regular Form to input the
  230.      search criteria.  The query results can be edited, or selected for
  231.      subsequent tagging operations.  You can use a variety of comparison
  232.      operators on each field, including "exact match", "doesn't equal
  233.      this", "contains this", "doesn't contain this", "begins with this",
  234.      "ends with this", etc.
  235.  
  236.      Normally a QBE Form is called from a QBE button on a Browse, although
  237.      it can be called from your own hand-coded procedures.  (Just set
  238.      GlobalRequest=QbeAction before calling the Form.)  The QBE button on
  239.      the browse usually has display text of "Search".  This button is
  240.      populated onto the Browse using the QbeBrowse Control template.
  241.  
  242.      The Form must have the QbeForm Control template.  This creates two
  243.      buttons:  "Search Type" and "Begin Search".  Depending on the type of
  244.      entry field, a different default comparison operator (Search Type) is
  245.      assumed.  The default is "begins with" for a string field, "equals
  246.      this" for a number field, etc.
  247.  
  248.      SuperQBE for CW is much more flexible that our CDD product.  You have
  249.      control of the defaults for String, Number, Picture, Date, Option,
  250.      Check, and Text fields.  You can modify these defaults in the template
  251.      settings.
  252.  
  253.      If the user wishes to override this default for a given field, they
  254.      must press the "Search Type" button to see a list of possible
  255.      comparison types.  This list is context sensitive:  it displays only
  256.      the applicable comparison types for the datatype of the current field.
  257.  
  258.      There is a corresponding one character "flag" to represent each of the
  259.      comparison operators.  The appropriate flag will appear in the
  260.      position immediately preceding the field, so you should make sure that
  261.      the field isn't positioned closely after another field or PROMPT(). 
  262.      If it is, the existing controls will be overlayed by the comparison
  263.      flags.  You can change the strings that are displayed using the global
  264.      prompts.  Some of the flags use the Symbol font, while others use the
  265.      System font.  You must make sure that these fonts are on your users'
  266.      systems.
  267.  
  268.      If the user enters more than one field in the form, the comparisons
  269.      are joined in a boolean "AND" operation.  For example, if the user
  270.      specifies a last name of "Smith", a city of "Toronto", and a salary of
  271.      more than "$50000", they will get only those records matching all
  272.      three of those criteria.  We will be adding the option for multiple
  273.      criteria values per field in a future version.  This would allow "OR"
  274.      operations like:  records where the last name is "Smith" or "Jones",
  275.      and they live in "Toronto" and ...
  276.  
  277.      Once they have finished entering the criteria, they can push the
  278.      "Begin Search" button, then choose to edit the results, or to select
  279.      all matching records.  This will actually vary depending on how you've
  280.  
  281.  
  282.                                       -3-      set up the prompts.  (For the time being, we'll assume that all
  283.      options are enabled.)
  284.  
  285.      If the user chooses to "Edit" the records, each matching record will
  286.      be displayed in the form.  The "Search Type" button is changed to
  287.      "Edit This", while the "Begin Search" button is changed to "Find
  288.      Next".  The "Cancel" button can be used to abort the search.  Once
  289.      they've accepted the first record they are immediately placed into
  290.      edit mode so that they can make any desired changes.  After finishing
  291.      the update, the form immediately returns to the calling procedure.
  292.  
  293.      If you have turned on the "Select Support", and if the user chooses to
  294.      "Select" the records, then all matching entries will be tagged.  You
  295.      can use the BrowseOptTagFilter, BrowseTagFilter, and ProcessTagFilter
  296.      templates to restrict which records are available.  If you have our
  297.      SuperTagging templates, you can also modify the selections using those
  298.      tagging features.  Make sure that all of the associated procedures use
  299.      the same tag storage settings.
  300.  
  301.      If there are already tagged records from a previous search, then the
  302.      user will be given an additional option of "Untagging".  This will
  303.      limit the search only to the previously-tagged records.  This is handy
  304.      if you want to find a bunch of records with one operation, then
  305.      selectively remove a few with a series of untag operations.
  306.  
  307.      For example, you may want to determine all people from Toronto who
  308.      don't live in an apartment.  You would first select all people who
  309.      live in Toronto.  Then you would perform a second query to unselect
  310.      those with "APT" in their address.  Then those with "SUITE", "STE",
  311.      etc.
  312.  
  313.      If there are previous tags but the user chooses to Select the records,
  314.      they will be given the option to clear the previous selections first. 
  315.      Depending on the type of data in your file, they may have handled the
  316.      "people in Toronto not in an apartment" example differently.  Rather
  317.      than performing a Select followed by various Unselects, they could
  318.      have done multiple Select operations.  The first would get all people
  319.      in Toronto where the address didn't contain "APT".  Each subsequent
  320.      search operation could add to the previous search's results.
  321.  
  322.      When searching for matching records, the system automatically uses
  323.      keys to optimize the operation.  First it checks the key specified in
  324.      your file schematic (if it exists).  Then it checks each key in the
  325.      order in which it appears in the file definition.  If the first field
  326.      in the key is specified in the criteria with an appropriate comparison
  327.      operator, it will use the key.
  328.  
  329.      Valid comparison operators include "exact match", "begins with", "in
  330.      range", "more than", "less than", "more than or equal", and "less than
  331.      or equal".  With this in mind, you may want to reorganize the keys in
  332.      your datafiles to optimize your searches.  For example, if you
  333.      anticipate that the user will perform many searches involving salary
  334.      ranges, then you might make the first key in your file based upon the
  335.      salary field.
  336.  
  337.  
  338.  
  339.  
  340.                                       -4-                                  --------------
  341.                                  What are Tags?
  342.                                  --------------
  343.  
  344.      Tags are "flags" on a record that indicate that they've been marked
  345.      for a special purpose.  There are three ways that tags can be stored
  346.      in the BoxSoft SuperTagging and SuperQBE templates:
  347.  
  348.      TagFile_ (POINTER)
  349.      ------------------
  350.  
  351.      This is the suggested method for storing tags, whenever possible.  
  352.      TagFile_ is a separate file using the TopSpeed file driver.  Each
  353.      record contains the user number, tag set number, record pointer, and
  354.      sorting value.  This enables you to have multiple users tagging
  355.      records in the file at the same time.  Or a single user could create
  356.      multiple tag sets for the same file (ie:  one for billing and another
  357.      for advertising).  There are three disadvantages to this method:
  358.  
  359.      1.   Because it is creating tags in a separate file, it is sometimes
  360.           slower than storing the tags in the primary data file itself.
  361.  
  362.      2.   The TagFile_ records are not relationally linked to the original
  363.           data file.  This means that you could delete a data record, and
  364.           have a tag hanging around.  (We will be addressing this issue in
  365.           an upcoming version.)
  366.  
  367.      3.   You can process the tags very quickly, but you don't have very
  368.           much control of the order in which the tags are processed.  There
  369.           is a field in the tag file called "Val" which stores a 10
  370.           character value that is used to control the ordering.  The
  371.           template decides which is the best field to use for this value.
  372.  
  373.  
  374.      TagFilePos_ (POSITION)
  375.      ----------------------
  376.  
  377.      Some file drivers do not support "record numbers", which means that
  378.      the POINTER function used with "TagFile_ (POSITION)" will not work. 
  379.      The most notable of these are the SQL drivers, which are tied to a
  380.      primary key value, rather than a record pointer.  For these files, we
  381.      offer the TagFilePos_ alternative.  It is identical to the previous
  382.      method, except that it use POSITION instead of POINTER.  Because of
  383.      this, it is marginally slower.  Other than that, it is has the same
  384.      pros and cons.
  385.  
  386.  
  387.      BYTE Field in Primary
  388.      ---------------------
  389.  
  390.      You can also store the tags by toggling a BYTE field in your data
  391.      file.  This has the benefit of being faster (if your records are not
  392.      too large), and you can use this field to index reports and processes. 
  393.      Unfortunately, it does not accommodate multi-user operations.  Multi-
  394.      Tag Sets can be accommodated by using multiple fields in the file.
  395.  
  396.  
  397.  
  398.                                       -5-                          ------------------------------
  399.                          Adding QBE to Your Application
  400.                          ------------------------------
  401.  
  402.  
  403.                             Registering the Template
  404.                             ------------------------
  405.  
  406.      CW allows you to have multiple template sets accessible in the same
  407.      application.  It does this with the Template Registry.  To use the
  408.      SuperQBE template, you must register it first.
  409.  
  410.      1.   Load CW, then select the "Setup / Template Registry" pulldown
  411.           menu option.
  412.  
  413.      2.   Press the "Register" button.
  414.  
  415.      3.   Select "C:\CW\SUPER\QBE.TPL".  (The directory name may not
  416.           exactly match your system.)
  417.  
  418.  
  419.                                  Global Support
  420.                                  --------------
  421.  
  422.      To use the QBE features, you must add the global support to your
  423.      application.  This is necessary because of a bug in CW 1.000.  With
  424.      future batches of CW, this will become easier.
  425.  
  426.      1.   Load your application.
  427.  
  428.      2.   Press the "Global" button on the "Application Tree" window.
  429.  
  430.      3.   Press the "Embed" button on the "Global Properties" window.
  431.  
  432.      4.   Highlight "Inside the Global Map", then press the "Add" button.
  433.  
  434.      5.   Locate "Class SuperQBE", then "GlobalMap" below that.  Highlight
  435.           this option and press the "Select" button.  There are a number of
  436.           prompts in this template:
  437.  
  438.           a)   "Support Select using the Tagging Library".  This controls
  439.                whether the tagging support library is included in the
  440.                global MAP.  If you want to select records without using a
  441.                Flag field in your file, then you will need leave this on.
  442.  
  443.           b)   "Job Selection Window".  This controls what the user sees
  444.                when they press the "Begin Search" button.
  445.  
  446.                i)   You can decide whether to support the Edit option, or
  447.                     whether Select/Unselect will be sufficient.  If your
  448.                     user needs QBE for generating reports rather than as an
  449.                     intelligent record finder, then you may want to turn
  450.                     this off.  Turning this off will disable various
  451.                     options below.
  452.  
  453.  
  454.  
  455.  
  456.                                       -6-                ii)  "Place Edit buttons before Select buttons".  If you
  457.                     want the order on the Qbe Job window as "Edit / Select
  458.                     / Unselect / Cancel", then turn this on.  If, instead,
  459.                     you prefer "Select / Unselect / Edit / Cancel", then
  460.                     turn it off.
  461.  
  462.                iii) The "Title" field is displayed at the top of the Qbe
  463.                     Job window.
  464.  
  465.                iv)  The next four options are for the button text.  If
  466.                     there are not any records currently selected, then the
  467.                     "Unselect" button will not appear.
  468.  
  469.           c)   The "Upper Limit Window" settings control the appearance of
  470.                your entry window.  You will only see this if you choose the
  471.                "Inside Range" or "Outside Range" comparison operators.
  472.  
  473.                The "Match Type Window" settings control the text that will          d)
  474.                appear when the user is choosing a comparison operator. 
  475.                Within this, the "Data Type Titles" button leads to the
  476.                window titles for different data types.  The "Buttons"
  477.                button leads you to the text settings for "OK" and "Cancel". 
  478.                The Match Type window automatically adjusts itself for the
  479.                size of the text that you specify.
  480.  
  481.                The "Match Type Flags" are the characters that are displayed          e)
  482.                in front of your fields for different comparison operators. 
  483.                If you are not happy with our choice of characters, you can
  484.                change them here.  You'll notice that the most of the
  485.                operators use the "Symbol" font, while the Date operators
  486.                use the "System" font.  This was a design decision.  If you
  487.                wish to control the font for each operator, then let us
  488.                know; then we can add it to a future version.
  489.  
  490.      6.   Highlight the "Global Data" embed entry, then press the "Add"
  491.           button.
  492.  
  493.      7.   Locate "Class SuperQBE", then "GlobalData" below that.  Highlight
  494.           this option and press the "Select" button.
  495.  
  496.           a)   "Support Select using the Tagging Library".  This controls
  497.                whether the tagging library's data references are included
  498.                in the Global Data area.  If you want to select records
  499.                without using a Flag field in your file, then you will need
  500.                leave this on.
  501.  
  502.      8.   Press the "Close" button on the "Embedded Source" window.
  503.  
  504.      9.   Press "OK" on the "Global Properties" window.
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.                                       -7-                                  Browse Support
  515.                                  --------------
  516.  
  517.      Normally you will be performing QBE operations by calling a Form from
  518.      a Browse.  First you have to add the QbeBrowse Control template to
  519.      your Browse screen.
  520.  
  521.      1.   Press the "Window" button on the "Procedure Properties" screen.
  522.  
  523.      2.   Arrange for a bit of space of your screen in which to place the
  524.           button.
  525.  
  526.      3.   Press the "TPL" button on the "Controls" Toolbox, or select the
  527.           "Populate / Control Template..." option from the pulldown menu.
  528.  
  529.      4.   Locate "Class SuperQBE", then "QbeBrowse" below that.  Highlight
  530.           this option and press the "Select" button.
  531.  
  532.      5.   As you move your cursor across your window structure, you will
  533.           notice the cursor changes to the "Populate Crosshairs".  Place
  534.           the cursor in the empty area, then click the left mouse button.
  535.  
  536.      6.   Adjust the size and position of the button as desired.  You can
  537.           change the button's text if it doesn't suit your situation.  Then
  538.           click the "OK" button to save the window structure.
  539.  
  540.      7.   Click the "Controls" button, highlight the "QBE Browse Control",
  541.           then press the "Properties" button.
  542.  
  543.      8.   The "Form Procedure" is the form that is called to perform the
  544.           search operation.  Normally this will be the same as your Update
  545.           Procedure.
  546.  
  547.      9.   The next setting is "Show only selected after successful search". 
  548.           It controls how the system behaves after your form has returned
  549.           to the Browse.  If this option is on, then the template will
  550.           attempt to find a "BrowseOptTagFilter" Control template to
  551.           display only tagged records.  If this prompt is turned off, or if
  552.           you do not have the BrowseOptTagFilter template populated onto
  553.           the Browse, then the browse will always show all records.
  554.  
  555.  
  556.  
  557.  
  558.  
  559.  
  560.  
  561.  
  562.  
  563.  
  564.  
  565.  
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.                                       -8-                                   Form Support
  573.                                   ------------
  574.  
  575.      This is where the bulk of the query operation is performed.  The
  576.      QbeForm Control template handles the user interface for entering the
  577.      search criteria, as well as performing the searching operations. 
  578.      There are a large number of settings to control the behaviour of the
  579.      system.
  580.  
  581.      1.   Press the "Window" button on the "Procedure Properties" screen.
  582.  
  583.      2.   Arrange for a bit of space of your screen in which to place the
  584.           two buttons.
  585.  
  586.      3.   Press the "TPL" button on the "Controls" Toolbox, or select the
  587.           "Populate / Control Template..." option from the pulldown menu.
  588.  
  589.      4.   Locate "Class SuperQBE", then "QbeForm" below that.  Highlight
  590.           this option and press the "Select" button.
  591.  
  592.      5.   As you move your cursor across your window structure, you will
  593.           notice the cursor changes to the "Populate Crosshairs".  Place
  594.           the cursor in the empty area, then click the left mouse button.
  595.  
  596.      6.   Adjust the size and position of the button as desired.  You can
  597.           change the button's text if it doesn't suit your situation.  Then
  598.           click the "OK" button to save the window structure.
  599.  
  600.      7.   Click the "Controls" button, highlight the "QBE Form Control",
  601.           then press the "Properties" button.
  602.  
  603.      8.   The first setting is "Buttons Unavailable".  This controls the
  604.           appearance of the two QBE buttons during normal editing
  605.           operations.  The default is "HIDE", altough you may want to
  606.           change it to "DISABLE".
  607.  
  608.      9.   The next setting is "Alternate Update Proc".  This is used when
  609.           you want this procedure to perform only searches, while another
  610.           procedure performs the actual edits to the file.  If you specify
  611.           this setting, it will call the alternate update procedure in two
  612.           situations:
  613.  
  614.           a)   The form is called with GlobalRequest <> QbeAction.
  615.  
  616.           b)   The user chooses to edit a record during the search.
  617.  
  618.      10.  The "'Select Records' Support" controls whether the user is
  619.           allowed to select records, and how those selections are stored.
  620.  
  621.                The first setting under this button controls whether          a)
  622.                selections are allowed at all.  If you turn this off, the
  623.                rest of the screen will be disabled.
  624.  
  625.                The next setting controls where tags are stored.  This can          b)
  626.                be "TagFile_ (POINTER)", "TagFilePos_ (POSITION)", or "BYTE
  627.                Field in Primary".  See the "What are Tags?" section earlier
  628.  
  629.  
  630.                                       -9-                in the manual for the pros and cons of each of these
  631.                methods.
  632.  
  633.           c)   If you chose TagFile_ or TagFilePos_ for the previous
  634.                option, you must specify a tag set number.
  635.  
  636.           d)   If you chose "BYTE Field" in the previous option, you must
  637.                specify a field from your file.
  638.  
  639.      11.  The "Miscellaneous Messages" button leads to a series of system
  640.           messages:
  641.  
  642.                "Enter Search Criteria (ActionMessage)".  This is the          a)
  643.                message that is displayed in your ActionMessage field during
  644.                the QBE criteria entry.
  645.  
  646.                "Select field before hitting Search Type".  The user must be          b)
  647.                sitting in a data field before hitting the "Search Type"
  648.                button.  Otherwise, the system doesn't know what field you
  649.                are working with.
  650.  
  651.                "Clear old selections first?".  This question is presented          c)
  652.                to the user if they decide to tag the query results but
  653.                there are existing tags present.
  654.  
  655.                "There are no matching records".  This message is displayed          d)
  656.                if there are no matching records.  This will only appear
  657.                when the system is search for the first matching record.
  658.  
  659.                "There are no more matching records".  This message is          e)
  660.                different from the previous entry in that it is called after
  661.                all records have been rejected during an "Edit" search.
  662.  
  663.                "You must specify at least one search field".  You cannot          f)
  664.                perform a "blank" query.  This message appears if the user
  665.                attempts to do so.
  666.  
  667.           g)   "Edit This Record?".  These last three settings control the
  668.                appearance of the ActionMessage and QBE Buttons during the
  669.                "Ask Edit" operation.
  670.  
  671.      12.  The "Progress Window" settings control what text is displayed on
  672.           the Progress screen.
  673.  
  674.      13.  The "Default Match Types" button leads to the default settings
  675.           for the different datatypes.  For example, you can individually
  676.           control the default comparison type for String, Number, Picture,
  677.           Date, Check, Option, and Text fields.
  678.  
  679.  
  680.  
  681.  
  682.  
  683.  
  684.  
  685.  
  686.  
  687.  
  688.                                       -10-                         Optional Tag Filters in a Browse
  689.                         --------------------------------
  690.  
  691.      Your users may wish to toggle between viewing "all records" and "only
  692.      tagged records".  The "BrowseOptTagFilter" Control template is
  693.      designed with this goal in mind.  It is populated onto the browse
  694.      window as a button that changes it's text depending on the current
  695.      viewing state.
  696.  
  697.      The QbeBrowse template will make use of this template to display only
  698.      selected records.
  699.  
  700.      Here's how you use the template:
  701.  
  702.      1.   Press the "Window" button on the "Procedure Properties" screen.
  703.  
  704.      2.   Arrange for a bit of space of your screen in which to place the
  705.           button.  If you have a group box around your tagging buttons,
  706.           then you may want to expand that group to place the new button
  707.           below.
  708.  
  709.      3.   Press the "TPL" button on the "Controls" Toolbox, or select the
  710.           "Populate / Control Template..." option from the pulldown menu.
  711.  
  712.      4.   Locate "Class SuperQBE", then "BrowseOptTagFilter" below that. 
  713.           Highlight this option and press the "Select" button.
  714.  
  715.      5.   As you move your cursor across your window structure, you will
  716.           notice the cursor changes to the "Populate Crosshairs".  Place
  717.           the cursor in the empty area, then click the left mouse button.
  718.  
  719.      6.   Adjust the size and position of the button as desired.  Don't
  720.           worry about the button's text, as this is controlled by the
  721.           template prompts.  Then click the "OK" button to save the window
  722.           structure.
  723.  
  724.      7.   Click the "Controls" button, highlight the "Optionally Filter
  725.           Tagged Records", then press the "Properties" button.
  726.  
  727.      8.   The first group is "Tag Storage".  Here you can specify the
  728.           location of the tags.  Your options are:
  729.  
  730.           TagFile_ (POINTER) - This method will cause tags to be stored in
  731.                a separate data file called TAGFILE_.TPS.  This is the
  732.                preferred method, as it provides the most flexibility, with
  733.                the best speed.
  734.  
  735.           TagFilePos_ (POSITION) - This is similar to the prior method,
  736.                except it is necessary when your data file driver doesn't
  737.                support record numbers (ie:  SQL).  It is slightly slower.
  738.  
  739.           BYTE Field in Primary - Using this method, all tags will be
  740.                stored as a True/False field in your file.
  741.  
  742.      9a.  If you choose either of the "TagFile" options, you will be asked
  743.           for a Tag Set Number or Equate.  This can be a constant (ie: 1),
  744.  
  745.  
  746.                                       -11-           an equate (ie: eT_Customer), or a variable (ie:  Loc:TodaysTags). 
  747.           At the very least, you should have a different Tag Set for each
  748.           data file; otherwise, there is a very good chance that your tag
  749.           sets will corrupt each other.  This field is required.
  750.  
  751.      9b.  If you choose "BYTE Field", you will be asked for the name of a
  752.           field in your BrowseBox's primary file.  This doesn't have to be
  753.           a BYTE field (any numeric field will do), but it makes the most
  754.           sense to save space.
  755.  
  756.      10.  The "Button Text" group controls the text that the user will see
  757.           on the button.  The "Show Tagged" message is displayed in the
  758.           button when they are viewing all records.  By pressing the
  759.           button, it will change the the "Show All" text, and they will be
  760.           viewing only tagged entries.  In each of these cases, you can
  761.           include an ampersand (&) to control the "hot key" for the button.
  762.  
  763.           The final option is a drop box controlling the initial state when
  764.           the user enters the browse.  The default for this is "Show All".
  765.  
  766.      11.  Press "OK" to save the "Prompts for BrowseOptTagFilter", "OK"
  767.           again to exit the "Edit Control Templates" window, and "OK" again
  768.           to save the "Procedure Properties".
  769.  
  770.      12.  Test you application.
  771.  
  772.  
  773.  
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786.  
  787.  
  788.  
  789.  
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797.  
  798.  
  799.  
  800.  
  801.  
  802.  
  803.  
  804.                                       -12-                    Filtering Tagged in Reports and Processes
  805.                    -----------------------------------------
  806.  
  807.      Your users may wish to toggle between viewing "all records" and "only
  808.      tagged records".  The "BrowseOptTagFilter" Control template is
  809.      designed with this goal in mind.  It is populated onto the browse
  810.      window as a button that changes it's text depending on the current
  811.      viewing state.  Here's how you do it:
  812.  
  813.      1.   Press the "Window" button on the "Procedure Properties" screen.
  814.  
  815.      2.   Arrange for a bit of space of your screen in which to place the
  816.           button.  If you have a group box around your tagging buttons,
  817.           then you may want to expand that group to place the new button
  818.           below.
  819.  
  820.      3.   Press the "TPL" button on the "Controls" Toolbox, or select the
  821.           "Populate / Control Template..." option from the pulldown menu.
  822.  
  823.      4.   Locate "Class SuperQBE", then "BrowseOptTagFilter" below that. 
  824.           Highlight this option and press the "Select" button.
  825.  
  826.      5.   As you move your cursor across your window structure, you will
  827.           notice the cursor changes to the "Populate Crosshairs".  Place
  828.           the cursor in the empty area, then click the left mouse button.
  829.  
  830.      6.   Adjust the size and position of the button as desired.  Don't
  831.           worry about the button's text, as this is controlled by the
  832.           template prompts.  Then click the "OK" button to save the window
  833.           structure.
  834.  
  835.      7.   Click the "Controls" button, highlight the "Optionally Filter
  836.           Tagged Records", then press the "Properties" button.
  837.  
  838.      8.   The first group is "Tag Storage".  Here you can specify the
  839.           location of the tags.  Your options are:
  840.  
  841.           TagFile_ (POINTER) - This method will cause tags to be stored in
  842.                a separate data file called TAGFILE_.TPS.  This is the
  843.                preferred method, as it provides the most flexibility, with
  844.                the best speed.
  845.  
  846.           TagFilePos_ (POSITION) - This is similar to the prior method,
  847.                except it is necessary when your data file driver doesn't
  848.                support record numbers (ie:  SQL).  It is slightly slower.
  849.  
  850.           BYTE Field in Primary - Using this method, all tags will be
  851.                stored as a True/False field in your file.
  852.  
  853.      9a.  If you choose either of the "TagFile" options, you will be asked
  854.           for a Tag Set Number or Equate.  This can be a constant (ie: 1),
  855.           an equate (ie: eT_Customer), or a variable (ie:  Loc:TodaysTags). 
  856.           At the very least, you should have a different Tag Set for each
  857.           data file; otherwise, there is a very good chance that your tag
  858.           sets will corrupt each other.  This field is required.
  859.  
  860.  
  861.  
  862.                                       -13-      9b.  If you choose "BYTE Field", you will be asked for the name of a
  863.           field in your BrowseBox's primary file.  This doesn't have to be
  864.           a BYTE field (any numeric field will do), but it makes the most
  865.           sense to save space.
  866.  
  867.      10.  The "Button Text" group controls the text that the user will see
  868.           on the button.  The "Show Tagged" message is displayed in the
  869.           button when they are viewing all records.  By pressing the
  870.           button, it will change the the "Show All" text, and they will be
  871.           viewing only tagged entries.  In each of these cases, you can
  872.           include an ampersand (&) to control the "hot key" for the button.
  873.  
  874.           The final option is a drop box controlling the initial state when
  875.           the user enters the browse.  The default for this is "Show All".
  876.  
  877.      11.  Press "OK" to save the "Prompts for BrowseOptTagFilter", "OK"
  878.           again to exit the "Edit Control Templates" window, and "OK" again
  879.           to save the "Procedure Properties".
  880.  
  881.      12.  Test you application.
  882.  
  883.  
  884.  
  885.  
  886.  
  887.  
  888.  
  889.  
  890.  
  891.  
  892.  
  893.  
  894.  
  895.  
  896.  
  897.  
  898.  
  899.  
  900.  
  901.  
  902.  
  903.  
  904.  
  905.  
  906.  
  907.  
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.                                       -14-                     Showing Only Tagged Records in a Browse
  921.                     ---------------------------------------
  922.  
  923.      This Extension template is similar to the "BrowseOptTagFilter" control
  924.      template.  It is used to display only tagged records on a Browse.  The
  925.      only difference is that this template has a fixed filter, rather than
  926.      giving the user the option of toggle between filtered and non-
  927.      filtered.  Accomplishing this is very simple:
  928.  
  929.      1.   This procedure can only be used with a procedure that already
  930.           contains a BrowseBox.  Get into the "Procedure Properties" screen
  931.           for your Browse, then press the "Extensions" button.
  932.  
  933.      2.   Press the "Add" button in the "Select Extension" window.
  934.  
  935.      3.   Locate the "Class SuperQBE", highlight "BrowseTagFilter" below
  936.           that, then press the "Select" button.
  937.  
  938.      4.   You will see the same storage options as were described in the
  939.           BrowseTaggingButtons section earlier.  Make sure that you specify
  940.           the same settings here as you did in your original tagging
  941.           Browse.  Otherwise, the tagged records will not be found.
  942.  
  943.      5.   Press "OK" in the "Prompts for BrowseTagFilter" window to return
  944.           to the "Edit Extensions" window.  Don't be alarmed when you
  945.           discover that your new extension has disappeared!  This is a bug
  946.           in Clarion.  Because this extension template is associated with a
  947.           control template, it has moved to the Controls window.  Press
  948.           "OK" to exit the "Edit Extensions" window.  You'll also notice
  949.           that there is a checkmark beside the "Extensions" button, even
  950.           though there is nothing in the window.
  951.  
  952.      6.   Press the "Controls" button on the "Procedure Properties" window,
  953.           highlight the "Filter Tagged Records" entry, then press the
  954.           "Properties" button.  Here are your settings.
  955.  
  956.      7.   Press three "OK" buttons, then test your application.
  957.  
  958.      Of course, if your browse used "BYTE Field in Primary" as its tag
  959.      storage method, then you don't need to use this extension.  Instead,
  960.      you could use a key on the tag field to make the Browse very fast. 
  961.      This is not really necessary unless you have many records in your
  962.      file.  We'll leave that up to your personal preference.
  963.  
  964.      If you need to delete this extension, you must press the "Window"
  965.      button, then select the "Edit / Control Templates..." pulldown menu
  966.      option.  You may highlight the template and press the "Delete" button
  967.      here.  At this time, this is only way to delete an Extension that
  968.      connected to a Control.
  969.  
  970.  
  971.  
  972.  
  973.  
  974.  
  975.  
  976.  
  977.  
  978.                                       -15-               Showing Only Tagged Records in Reports and Processes
  979.               ----------------------------------------------------
  980.  
  981.      Once your user has tagged records, he will want to do something when
  982.      them.  The most common request is to print only tagged records in a
  983.      report.  Or they may want to delete the tagged records using a Process
  984.      procedure.  Accomplishing this is very simple:
  985.  
  986.      1.   Get into the "Procedure Properties" screen for your Report or
  987.           Process, press the "Extensions" button.
  988.  
  989.      2.   Press the "Add" button in the "Select Extension" window.
  990.  
  991.      3.   Locate the "Class SuperQBE", highlight the "ProcessTagFilter"
  992.           below that, then press the "Select" button.
  993.  
  994.      4.   You will see the same storage options as were described in the
  995.           BrowseTaggingButtons section earlier.  Make sure that you specify
  996.           the same settings here as you did in your Browse.  Otherwise, the
  997.           tagged records will not be found.
  998.  
  999.      5.   Save the process and test your APP.
  1000.  
  1001.      Of course, if your browse used "BYTE Field in Primary" as its tag
  1002.      storage method, then you don't need to use this extension.  Instead,
  1003.      you could use a key on the tag field to speed up the report.  We'll
  1004.      leave that up to your personal preference.
  1005.  
  1006.  
  1007.  
  1008.  
  1009.  
  1010.  
  1011.  
  1012.  
  1013.  
  1014.  
  1015.  
  1016.  
  1017.  
  1018.  
  1019.  
  1020.  
  1021.  
  1022.  
  1023.  
  1024.  
  1025.  
  1026.  
  1027.  
  1028.  
  1029.  
  1030.  
  1031.  
  1032.  
  1033.  
  1034.  
  1035.  
  1036.                                       -16-                                -----------------
  1037.                                Reference Section
  1038.                                -----------------
  1039.  
  1040.      Embed Points in QbeForm
  1041.      -----------------------
  1042.  
  1043.      The QbeForm template creates its own ACCEPT loop for entering the QBE
  1044.      criteria.  This means that none of your regular EVENT, SELECTED and
  1045.      ACCEPTED embed points will be included during the criteria entry
  1046.      stage.  This is normally not a problem.  If, however, you wish to
  1047.      tweak the QBE operation, you'll find the following embed points for
  1048.      your use:
  1049.  
  1050.      QBE:  Before Opening the Window - This is executed before the
  1051.           OPEN(%Window) statement.
  1052.  
  1053.      QBE:  After Opening the Window - This is executed after the
  1054.           OPEN(%Window) statement.  The system has already hidden all of
  1055.           the non-QBE controls and created all of the Match Type flags.
  1056.  
  1057.      QBE:  Preparing to Process the Window - This occurs immediately before
  1058.           the ACCEPT loop.
  1059.  
  1060.      QBE:  Accept Loop, Before CASE EVENT() handling - This occurs
  1061.           immediately inside the ACCEPT loop.
  1062.  
  1063.      QBE:  Accept Loop, After CASE FIELD() handling - This occurs at the
  1064.           bottom of the ACCEPT loop, after the built-in EVENT() and FIELD()
  1065.           processing.
  1066.  
  1067.      If you wish to perform event processing, then you must write the case
  1068.      structures yourself.  The basic for is:
  1069.  
  1070.           CASE EVENT()
  1071.           OF EVENT:Selected
  1072.             CASE SELECTED()
  1073.             OF ?YourField
  1074.               DO Something
  1075.             END
  1076.           OF EVENT:Accepted
  1077.             CASE ACCEPTED()
  1078.             OF ?YourField
  1079.               DO SomethingElse
  1080.             END
  1081.           OF EVENT:Timer
  1082.             DO TimerCode
  1083.           END
  1084.  
  1085.      There is one final embed:  Hidden QBE Criteria.  In some situations,
  1086.      your QBE operation must search within a standard set of records.  For
  1087.      example, you might restrict the searches to transactions from this
  1088.      year, or to records assigned to the current user.  You don't want to
  1089.      force the user to enter this criteria each time.  In the case of user-
  1090.      specific records, there may be security issues involved.  This embed
  1091.  
  1092.  
  1093.  
  1094.                                       -17-      point is designed to handle this problem.  You can add as many hidden
  1095.      criteria as you need.  The code will look something like this:
  1096.  
  1097.           IF NOT Condition THEN EXIT.
  1098.           IF YEAR(Inv:Date) <> YEAR(TODAY()) THEN EXIT.
  1099.           IF Cus:UserNo <> UserNo_ THEN EXIT.
  1100.  
  1101.  
  1102.      Global Variables
  1103.      ----------------
  1104.  
  1105.      If you wish to override the default for these variables, you should do
  1106.      it in the "Setup Program" global embed.
  1107.  
  1108.      TagFile::Name       This contains the name of the TagFile used for
  1109.                          tagging with the POINTER function.  The default is
  1110.                          "TAGFILE_.TPS".
  1111.  
  1112.      TagFilePos::Name    This contains the name of the TagFile used for
  1113.                          tagging with the POSITION function.  The default
  1114.                          is "TAGFILEP.TPS".
  1115.  
  1116.      TagFile::Access     This is the access mode used to open the POINTER
  1117.                          tag file.  The default is 42h, which is the
  1118.                          standard "sharing" mode.  If your application is
  1119.                          single-user, then you can change this to 22h.  We
  1120.                          have found that using 42h keeps the application
  1121.                          acceptably quick using the TopSpeed file driver.
  1122.  
  1123.      TagFilePos::Access  This is the same as TagFile::Access, except for
  1124.                          the POSITION library.
  1125.  
  1126.      TagFile::Used       This is equivalent to the "Filename::Used"
  1127.                          variables that are generated for each of your
  1128.                          application's data files.  It is incremented each
  1129.                          time the TagFile_ is opened, and decremented with
  1130.                          the process is finished.
  1131.  
  1132.      TagFilePos::Used    This is the same as "TagFile::Used", except for
  1133.                          the TagFilePos_ file.
  1134.  
  1135.      UserNo_             This global variable is actually populated
  1136.                          directly into your global data variables.  It is
  1137.                          used by the tagging system to support multi-user
  1138.                          operations.  It is also used by the BoxSoft
  1139.                          SuperSecurity Template.  If you are not using the
  1140.                          BoxSoft security features, then you can set this
  1141.                          variable to match your user number before
  1142.                          beginning any tagging operations.
  1143.  
  1144.  
  1145.  
  1146.  
  1147.  
  1148.  
  1149.  
  1150.  
  1151.  
  1152.                                       -18-      Procedures and Functions using POINTER
  1153.      --------------------------------------
  1154.  
  1155.      If you are using the "TagFile_ (POINTER)" storage method, then the
  1156.      following procedures and functions apply:
  1157.  
  1158.      NewTag_        This procedure clears all tags for a specified tag set. 
  1159.                     The format of its call is:
  1160.  
  1161.                          NewTag_(<tag set>)
  1162.  
  1163.      CntTag_        This function returns the number of tags in the
  1164.                     specified tag set.  The format of its call is:
  1165.  
  1166.                          Result# = CntTag_(<tag set>)
  1167.  
  1168.      GetTag_        This function returns either 1 or 0, depending on
  1169.                     whether the requested record is tagged.  The format of
  1170.                     its call is:
  1171.  
  1172.                          Result# = GetTag_(<tag set>, <record pointer>)
  1173.  
  1174.                          IF GetTag_(1,POINTER(Customer))                    ie:
  1175.                            DO Process
  1176.                          END
  1177.  
  1178.      SetTag_        This procedure is used to set a tag for a particular
  1179.                     tag set and record pointer.  There is an optional Value
  1180.                     parameter, for storing the tags in a particular order
  1181.                     for FstTag_/NxtTag_ processing.  The format of its call
  1182.                     is:
  1183.  
  1184.                          SetTag_(<tag set>, <record pointer>, <value>)
  1185.  
  1186.                     ie:  SetTag_(1,POINTER(Product))
  1187.  
  1188.                          SetTag_(1,POINTER(Customer),Cst:LName)                    ie:
  1189.  
  1190.      ClrTag_        This procedure is used to clear a tag for a particular
  1191.                     tag set and record pointer.  The format of its call is:
  1192.  
  1193.                          ClrTag_(<tag set>, <record pointer>, <value>)
  1194.  
  1195.                     ie:  ClrTag_(1,POINTER(Customer))
  1196.  
  1197.  
  1198.  
  1199.  
  1200.  
  1201.  
  1202.  
  1203.  
  1204.  
  1205.  
  1206.  
  1207.  
  1208.  
  1209.  
  1210.                                       -19-      RvsTag_        This procedure is used to reverse a tag for a
  1211.                     particular tag set and record pointer.  That is, if the
  1212.                     tag is set before the call to RvsTag_ it will be
  1213.                     cleared, and vice versa.  There is an optional Value
  1214.                     parameter, for storing the tags in a particular order
  1215.                     for FstTag_/NxtTag_ processing.  The format of its call
  1216.                     is:
  1217.  
  1218.                          RvsTag_(<tag set>, <record pointer>, <value>)
  1219.  
  1220.                          RvsTag_(1,POINTER(Product))                    ie:
  1221.  
  1222.                          RvsTag_(1,POINTER(Customer),Cst:LName)
  1223.  
  1224.      FstTag_        This function returns a pointer to the first tagged
  1225.                     record in the specified tag set.  If there are no
  1226.                     records in the specified tag set, the function returns
  1227.                     zero.  It processes the tags in TF_:ValKey order, which
  1228.                     is usually the order of the original browse or order
  1229.                     that the records were tagged.
  1230.  
  1231.                     There are a number of situations where you would use
  1232.                     FstTag_().  You may want to check if there are any
  1233.                     tagged records available.  You would also use FstTag_()
  1234.                     in conjunction with NxtTag_() to process all tagged
  1235.                     records.  The format of its call is:
  1236.  
  1237.                          Result# = FstTag_(<tag set>)
  1238.  
  1239.      NxtTag_        This function returns a pointer to the next tagged
  1240.                     record in the specified tag set.  FstTag_() must be
  1241.                     called first for this function to work.  If there are
  1242.                     no more records, the function returns zero.  The format
  1243.                     of its call is:
  1244.  
  1245.                          Result# = NxtTag_(<tag set>)
  1246.  
  1247.      LstTag_        This function returns a pointer to the last tagged
  1248.                     record in the specified tag set.  If there are no
  1249.                     records in the specified tag set, the function returns
  1250.                     zero.  It processes the tags in reverse TF_:ValKey
  1251.                     order
  1252.  
  1253.                     There are a number of situations where you would use
  1254.                     LstTag_().  You may want to check if there are any
  1255.                     tagged records available.  You would also use LstTag_()
  1256.                     in conjunction with PrvTag_() to process all tagged
  1257.                     records.  The format of its call is:
  1258.  
  1259.                          Result# = LstTag_(<tag set>)
  1260.  
  1261.  
  1262.  
  1263.  
  1264.  
  1265.  
  1266.  
  1267.  
  1268.                                       -20-      PrvTag_        This function returns a pointer to the next tagged
  1269.                     record in the specified tag set.  LstTag_() must be
  1270.                     called first for this function to work.  If there are
  1271.                     no more records, the function returns zero.  The format
  1272.                     of its call is:
  1273.  
  1274.                          Result# = PrvTag_(<tag set>)
  1275.  
  1276.  
  1277.      Procedures and Functions using POSITION
  1278.      ---------------------------------------
  1279.  
  1280.      If you are using the "TagFilePos_ (POSITION)" storage method, then the
  1281.      following procedures and functions apply:
  1282.  
  1283.      NewTagPos_     This procedure clears all tags for a specified tag set. 
  1284.                     The format of its call is:
  1285.  
  1286.                          NewTagPos_(<tag set>)
  1287.  
  1288.      CntTagPos_     This function returns the number of tags in the
  1289.                     specified tag set.  The format of its call is:
  1290.  
  1291.                          Result# = CntTagPos_(<tag set>)
  1292.  
  1293.      GetTagPos_     This function returns either 1 or 0, depending on
  1294.                     whether the requested record is tagged.  The format of
  1295.                     its call is:
  1296.  
  1297.                          Result# = GetTag_(<tag set>, <record position>)
  1298.  
  1299.                     ie:  IF GetTagPos_(1,POSITION(Customer))
  1300.                            DO Process
  1301.                          END
  1302.  
  1303.      SetTagPos_     This procedure is used to set a tag for a particular
  1304.                     tag set and record position.  There is an optional
  1305.                     Value parameter, for storing the tags in a particular
  1306.                     order for FstTagPos_/NxtTagPos_ processing.  The format
  1307.                     of its call is:
  1308.  
  1309.                          SetTagPos_(<tag set>, <record position>, <value>)
  1310.  
  1311.                          SetTagPos_(1,POSITION(Product))                    ie:
  1312.  
  1313.                          SetTagPos_(1,POSITION(Customer),Cst:LName)                    ie:
  1314.  
  1315.      ClrTagPos_     This procedure is used to clear a tag for a particular
  1316.                     tag set and record position.  The format of its call
  1317.                     is:
  1318.  
  1319.                          ClrTagPos_(<tag set>, <record position>, <value>)
  1320.  
  1321.                     ie:  ClrTagPos_(1,POSITION(Customer))
  1322.  
  1323.  
  1324.  
  1325.  
  1326.                                       -21-      RvsTagPos_     This procedure is used to reverse a tag for a
  1327.                     particular tag set and record position.  That is, if
  1328.                     the tag is set before the call to RvsTagPos_ it will be
  1329.                     cleared, and vice versa.  There is an optional Value
  1330.                     parameter, for storing the tags in a particular order
  1331.                     for FstTagPos_/NxtTagPos_ processing.  The format of
  1332.                     its call is:
  1333.  
  1334.                          RvsTagPos_(<tag set>, <record position>, <value>)
  1335.  
  1336.                          RvsTagPos_(1,POSITION(Product))                    ie:
  1337.  
  1338.                          RvsTagPos_(1,POSITION(Customer),Cst:LName)
  1339.  
  1340.      FstTagPos_     This function returns the position of the first tagged
  1341.                     record in the specified tag set.  If there are no
  1342.                     records in the specified tag set, the function returns
  1343.                     an empty string ('').  It processes the tags in
  1344.                     TP_:ValKey order, which is usually the order of the
  1345.                     original browse or order that the records were tagged.
  1346.  
  1347.                     There are a number of situations where you would use
  1348.                     FstTagPos_().  You may want to check if there are any
  1349.                     tagged records available.  You would also use
  1350.                     FstTagPos_() in conjunction with NxtTagPos_() to
  1351.                     process all tagged records.  The format of its call is:
  1352.  
  1353.                          Result" = FstTagPos_(<tag set>)
  1354.  
  1355.      NxtTagPos_     This function returns the position of the next tagged
  1356.                     record in the specified tag set.  FstTagPos_() must be
  1357.                     called first for this function to work.  If there are
  1358.                     no more records, the function returns an empty string
  1359.                     ('').  The format of its call is:
  1360.  
  1361.                          Result" = NxtTagPos_(<tag set>)
  1362.  
  1363.      LstTagPos_     This function returns the position of the last tagged
  1364.                     record in the specified tag set.  If there are no
  1365.                     records in the specified tag set, the function returns
  1366.                     an empty string ('').  It processes the tags in reverse
  1367.                     TP_:ValKey order
  1368.  
  1369.                     There are a number of situations where you would use
  1370.                     LstTagPos_().  You may want to check if there are any
  1371.                     tagged records available.  You would also use
  1372.                     LstTagPos_() in conjunction with PrvTagPos_() to
  1373.                     process all tagged records.  The format of its call is:
  1374.  
  1375.                          Result" = LstTagPos_(<tag set>)
  1376.  
  1377.  
  1378.  
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384.                                       -22-      PrvTagPos_     This function returns the position of the next tagged
  1385.                     record in the specified tag set.  LstTagPos_() must be
  1386.                     called first for this function to work.  If there are
  1387.                     no more records, the function returns an empty string
  1388.                     ('').  The format of its call is:
  1389.  
  1390.                          Result" = PrvTagPos_(<tag set>)
  1391.  
  1392.  
  1393.      Miscellaneous Procedures and Functions
  1394.      --------------------------------------
  1395.  
  1396.      UsrTag_        This procedure is used to set the pointer to the global
  1397.                     UserNo_ variable.  This variable is shared by the
  1398.                     BoxSoft SuperSecurity Templates so that your tagging
  1399.                     operations are automatically multi-user when using the
  1400.                     security system.
  1401.  
  1402.  
  1403.  
  1404.  
  1405.  
  1406.  
  1407.  
  1408.  
  1409.  
  1410.  
  1411.  
  1412.  
  1413.  
  1414.  
  1415.  
  1416.  
  1417.  
  1418.  
  1419.  
  1420.  
  1421.  
  1422.  
  1423.  
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  
  1429.  
  1430.  
  1431.  
  1432.  
  1433.  
  1434.  
  1435.  
  1436.  
  1437.  
  1438.  
  1439.  
  1440.  
  1441.  
  1442.                                       -23-                           ----------------------------
  1443.                           Contacting Technical Support
  1444.                           ----------------------------
  1445.  
  1446.  
  1447.      If you have any troubles with this product, then please contact:
  1448.  
  1449.  
  1450.                          Mitten Software
  1451.                          10709 Wayzata Blvd
  1452.                          Minnetonka, MN  55305
  1453.  
  1454.                          Voice    : (612) 593-5019
  1455.                          Fax      : (612) 593-5028
  1456.                          BBS      : (612) 593-1050
  1457.                          CIS      : Mike Hanson [73234,1447]
  1458.                          Internet : 73234.1447@compuserve.com
  1459.  
  1460.  
  1461.  
  1462.  
  1463.  
  1464.  
  1465.  
  1466.  
  1467.  
  1468.  
  1469.  
  1470.  
  1471.  
  1472.  
  1473.  
  1474.  
  1475.  
  1476.  
  1477.  
  1478.  
  1479.  
  1480.  
  1481.  
  1482.  
  1483.  
  1484.  
  1485.  
  1486.  
  1487.  
  1488.  
  1489.  
  1490.  
  1491.  
  1492.  
  1493.  
  1494.  
  1495.  
  1496.  
  1497.  
  1498.  
  1499.  
  1500.                                       -24-